home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / CLT141.ARJ / README < prev    next >
Text File  |  1992-03-18  |  24KB  |  553 lines

  1.                                   CLINT V1.41
  2.                                   ───────────
  3.                                          
  4.                       The Ultimate C Source Checking Tool
  5.                                          
  6.                  (c) 1992 R&D Associates - All Rights Reserved
  7.       
  8.           ┌──────────────────────────────────────────────────────────┐
  9.           │                                                          │
  10.           │         R&D Associates, 16 High Street, Rainham,         │
  11.           │                  Kent ENGLAND, ME8 7JE                   │
  12.           │                                                          │
  13.           │                    Tel: (0634) 361668                    │
  14.           │                                                          │
  15.           ├──────────────────────────────────────────────────────────┤
  16.           │                                                          │
  17.           │       ** NEW **  R&D Associates can be contacted on      │
  18.           │       COMPUSERVE by mailing user ID:                     │
  19.           │                                                          │
  20.           │                      100013,1042                         │
  21.           │                                                          │
  22.           └──────────────────────────────────────────────────────────┘
  23.       
  24.  
  25.                                  **** NEW ****
  26.                                  ─────────────
  27.  
  28.      In V1.41 added -x  switch which releases 50K more memory to CLint, but
  29.      makes checking fractionally slower. Great for BorlandC++ with Windows!
  30.  
  31.  
  32.                                  WHAT IS CLINT?
  33.                                  ──────────────
  34.  
  35.      CLint is a tool which reads the source files of your C  programs,  and
  36.      generates  reports about possible problems.  As it can look at ALL the
  37.      files in a program,  it is able to report far more than any C compiler
  38.      can.  Use CLint while developing your  programs, and you'll be assured
  39.      of type safe linkage, efficient code, and excellent portability.
  40.  
  41.      This version of  CLint is released as  SHAREWARE.  This means that you
  42.      use it on a try-before-you-buy basis.  If you find  CLint useful,  you
  43.      must register.  We'll  then send  you  the latest  version, with  more
  44.      documentation,  and  you'll  receive  news of  updates  and  technical
  45.      support.  R&D Associates  regrets  that it  is  unable to  provide any
  46.      support for it's shareware products without registration.  Please read
  47.      the file LICENSE.DOC for more details.
  48.  
  49.  
  50.                                   INSTALLATION
  51.                                   ────────────
  52.       
  53.      PLEASE NOTE: If you already have a CLINT.CFG file you should rename it
  54.      to   CLINT.OLD  before   installing  this  upgrade   and  then,  after
  55.      installation, type:
  56.       
  57.           COPY CLINT.OLD CLINT.CFG
  58.       
  59.      Otherwise your current configuration settings will be lost. To install
  60.      this  version of CLint insert the supplied CLint disk in the drive (we
  61.      assume drive A: here), then type:
  62.       
  63.           A:
  64.           SETUP C:\CLINT
  65.       
  66.      assuming  C:\CLINT  is  the  directory  you  want  the  program  to be
  67.      installed  in.  Select the  compiler you're  using, and  specify where
  68.      you're  compiler lives.  SETUP writes the  CLINT.CFG file accordingly.
  69.      You can use SETUP again at any time to change these choices.
  70.  
  71.      Alternatively,  if you downloaded CLint from a bulletin board,  expand
  72.      it into the directory of your choice,  then type  SETUP to select your
  73.      compiler.
  74.  
  75.      Having installed  CLint  the first thing  you may need to do is modify
  76.      your AUTOEXEC.BAT file to include the line:
  77.       
  78.           SET CLINT=C:\CLINT
  79.       
  80.      or similar if you installed to a different directory.
  81.       
  82.      If  you use a ram disk, CLint will  run faster if you tell it to place
  83.      it's  temporary files on ram disk. Assuming you have a ram disk called
  84.      D: then also add to the following line to your AUTOEXEC.BAT file:
  85.       
  86.           SET TMP=D: (or E: etc.)
  87.      or
  88.           SET TEMP=D:
  89.       
  90.                WARNING:  Don't specify  a nonexistent  name here,  or CLint
  91.                won't work!
  92.       
  93.      Then  you should modify your path to include CLint's directory, or (if
  94.      your  path is  already long)  you can  place the  following batch file
  95.      CLINT.BAT in a directory already in your path:
  96.       
  97.           @ECHO OFF
  98.           C:\CLINT\CLINT %1 %2 %3 %4 %5 %6 %7 %8 %9
  99.       
  100.      Finally,  you must execute in your CLint directory the batch file most
  101.      closely matching your compiler.  This will construct the CLint library
  102.      for the compiler. The files are:
  103.  
  104.          CTC20.BAT               TurboC 2.0 or earlier
  105.          CTCPP10.BAT             TurboC++ 1.0
  106.          CBCPP30.BAT             Borland C++ 3.0 or earlier
  107.          CMSC6.BAT               Microsoft C 6.0 or earlier
  108.          CZTC21.BAT              Zortech C++ 2.1 or earlier
  109.  
  110.      If you are not using one of the above compilers, use CTC20.BAT.
  111.  
  112.      Now re-boot your computer to allow the changes to AUTOEXEC.BAT to take
  113.      effect.
  114.       
  115.                PLEASE  NOTE: If you change your  version of C you will need
  116.                to  run SETUP  from the  CLint directory  when you  make the
  117.                change.
  118.  
  119.                                CONFIGURING CLINT
  120.                                ─────────────────
  121.       
  122.      You  can configure CLint  to your personal  preferences by editing the
  123.      supplied  CLINT.CFG file  which looks  like this  (varies according to
  124.      what you told SETUP when CLint was installed):
  125.       
  126.           # (c) R&D Associates 1992.
  127.           # CLINT.CFG
  128.           -IC:\TC\INCLUDE         # TurboC++ 1.0
  129.           -lC:\CLINTREG\CTCPP10   # Clint Library for TurboC++ 1.0
  130.           #
  131.           # Add additional include directories with -I
  132.           # Add your Clint library directory with -l
  133.           # Add your common Clint warning switches:
  134.           # -wxxx to enable warning xxx,
  135.           # -w-xxx to diable warning xxx.
  136.           #
  137.       
  138.      As you will see later, you can add any of CLint's options to this file
  139.      as  you see  fit. The  '-I' line specifies  the name  of the directory
  140.      where your compilers's header files are - change this as required. The
  141.      '-l'  line specifies where  you keep the  library definitions, and the
  142.      name of the definition file.
  143.       
  144.            ─────────────────────────────────────────────────────────
  145.            NOTE: You MUST specify complete pathnames with -I and -l!
  146.            ─────────────────────────────────────────────────────────
  147.       
  148.      CLint  searches for  CLINT.CFG in the  current directory,  then in the
  149.      directory  specified  in  the CLint  environment  (SET)  variable. You
  150.      should  setup  the standard  CLINT.CFG  file to  reflect  your general
  151.      needs.  If a special case arises in  one of your programs, simply copy
  152.      CLINT.CFG to that directory:
  153.       
  154.           CD MYDIR
  155.           COPY \CLINT\CLINT.CFG
  156.       
  157.      and edit it as required. No other use of CLint will be affected. CLint
  158.      expects  that each  line in CLINT.CFG  is a CLint  option which starts
  159.      with  '-' and is followed by an  option letter, and any required text.
  160.      Any  number of  other lines  may be  present in  the file  and will be
  161.      ignored. You can also comment any line by using '#' like this:
  162.       
  163.           -l\clint\cbcpp30    # BorlandC++ 3.0
  164.       
  165.      Such comments are ignored. CLint is insensitive to case in the command
  166.      line or in CLINT.CFG except as detailed later.
  167.  
  168.  
  169.                                   USING CLINT
  170.                                   ───────────
  171.       
  172.      In the simplest case, you will use CLint like this:
  173.       
  174.           CLINT *.C
  175.       
  176.      CLint  will read all of the  source files, analyse them carefully, and
  177.      report on any possibly problems, ANSI violations, portability problems
  178.      and  so forth. It assumes that all the files specified are part of one
  179.      program,  and will  be linked together,  and linked  with the run-time
  180.      library  routines specified in  CLINT.CFG or with  '-l' options on the
  181.      command line.
  182.       
  183.      It  checks carefully  that symbols  declared in  one file  and used in
  184.      another  have the same  declaration in both  files; that all functions
  185.      defined  are actually called; that all  variables defined are used. If
  186.      CLint  produces no  warnings or errors  about such things,  you can be
  187.      assured that the program when linked is type-safe.
  188.       
  189.      There may be cases where you have run-time libraries supplied by other
  190.      vendors,  or written  by yourself. You  will need to  tell CLint about
  191.      them  to obtain full checking. If you don't, CLint will complain about
  192.      symbols which are never defined.
  193.       
  194.      Let's assume that you have a library called MYLIB in \MYLIB, which has
  195.      a  header MYLIB.H. The first  thing to do is  verify that there are no
  196.      errors in MYLIB:
  197.       
  198.           CD \MYLIB
  199.           CLINT *.C
  200.       
  201.      Fix any errors reported before proceeding! Then you do:
  202.       
  203.           CLINT MYLIB.H -L MYLIBDEF
  204.       
  205.      And finally you add the line:
  206.       
  207.           -l\MYLIB\MYLIBDEF
  208.       
  209.      to  CLINT.CFG. (If you  don't want to  add this line,  simply type the
  210.      '-l' option when you run CLint.)
  211.       
  212.      The really important options you may need to use are:
  213.       
  214.           -Dname=value   define a preprocessor macro
  215.           -Uname         undefine a preprocessor macro
  216.           -lfile         specify a CLint library file to check against
  217.       
  218.      When   reading  header  files,   CLint  distinguishes  between  header
  219.      directories specified in CLINT.CFG, and those specified in the command
  220.      line.  The former  are assumed to  be your compiler  or library header
  221.      files, the latter header files which are part of the program.
  222.       
  223.      This  is  only  important  when '-w-shd'  is  used  (don't  warn about
  224.      compiler headers - the default), as CLint will only be silent on minor
  225.      problems in compiler headers - not program ones.
  226.       
  227.      The search order for headers which use "file.h" is:
  228.       
  229.           1) Current directory,
  230.       
  231.           2) Directories given in -I in the command,
  232.       
  233.           3) Directories given in -I in CLINT.CFG.
  234.       
  235.      For headers which use <file.h> only (2) and (3) are searched.
  236.       
  237.      The  built-in preprocessor is  a full ANSI  implementation. It defines
  238.      the required preprocessor macros:
  239.       
  240.           __LINE__, __FILE_, __DATE__, __TIME__
  241.       
  242.      and also the macros
  243.       
  244.           __DOS__ and __CLINT__
  245.       
  246.      with  the value '1'. If you require __STDC__ place '-D__STDC__' on the
  247.      command line or in CLINT.CFG.
  248.       
  249.      Some  users have encountered problems with compilers which claim to be
  250.      ANSI, but don't have fully ANSI preprocessors. Lines like:
  251.       
  252.           #ifdef (sizeof(int) == sizeof(short))
  253.       
  254.      often  in LIMITS.H are a dead giveaway. The ANSI standard specifically
  255.      prohibits  expressions  like this:  you can't  have casts,  sizeof, or
  256.      enumeration  constants  in a  #if expression.  It  is usually  done by
  257.      compilers that are trying to deduce the model you are using. Compliant
  258.      compilers define preprocessor symbols instead.
  259.  
  260.  
  261.                            THE COMMAND LINE OPTIONS.
  262.                            ─────────────────────────
  263.       
  264.      CLint  takes a number  of source file  names, possibly with wildcards,
  265.      and  analyses these sources. To control  the analysis and reporting, a
  266.      number   of  options  may  occur  on  the  command  line,  or  in  the
  267.      configuration file CLINT.CFG.
  268.       
  269.      The  filenames may be specified in full  or in part. Filenames with no
  270.      extension  are  assumed  to have  the  extension '.C'.  The  files are
  271.      inspected  in order of their occurance  on the command line. When wild
  272.      card expansion occurs, the expanded names are ordered alphabetically.
  273.       
  274.      All  clint  options  begin with  a  leading '-'  character.  Except as
  275.      described below, options are case insensetive unless the C standard or
  276.      operating system requires otherwise.
  277.       
  278.      Options  may occur in  any order on the  command line, intermixed with
  279.      file names. The options are read in the order:
  280.       
  281.           CLINT.CFG
  282.      and
  283.           command line left-to-right
  284.       
  285.      which  can  be important.  Options in  the  command line  may override
  286.      options in CLINT.CFG or earlier options in the command line.
  287.       
  288.      ──────────────────────────────────────────────────────────────────────
  289.      NOTE: CLint searches for CLINT.CFG first in the current directory, and
  290.      then  in the directory  specified in your  CLINT environment variable.
  291.      CLint issues no warnings if CLINT.CFG can't be found.
  292.      ──────────────────────────────────────────────────────────────────────
  293.       
  294.      Typing:
  295.       
  296.           clint
  297.       
  298.      produces a usage screen summarising the options.
  299.  
  300.      ──────────────────────────────────────────────────────────────────────
  301.           -Ipath
  302.           -ipath
  303.       
  304.      'path'  is a directory name. Case  may be important in directory names
  305.      depending on the operating system you use. It specifies a directory to
  306.      search  for header  files. There  may be as  many of  these options as
  307.      required. The order of search for:
  308.       
  309.           #include "file"
  310.       
  311.      is
  312.       
  313.           current directory,
  314.           -I directories given on the command line,
  315.           -I directories given in CLINT.CFG.
  316.       
  317.      and for:
  318.       
  319.           #include <file>
  320.       
  321.      is
  322.       
  323.           -I directories given on the command line,
  324.           -I directories given in CLINT.CFG.
  325.       
  326.      You  can force  CLint to  forget all  the -I  options in  CLINT.CFG by
  327.      giving  '-I-' or '-i-' on the command  line prior to any other include
  328.      paths.
  329.       
  330.      ──────────────────────────────────────────────────────────────────────
  331.           -Dname
  332.           -dname
  333.           -Dname=value
  334.           -dname=value
  335.       
  336.      This  option defines a preprocessor  macro. Although the option letter
  337.      is  case insensetive,  the macro names  and values are  NOT. The first
  338.      form  defines a  macro with default  replacement text  '1'. The second
  339.      form  gives the replacement text explicitly. For your convenience, you
  340.      may append several definitions to an option with ';' like this:
  341.       
  342.           -Dname1;name2=4;name3=5;name4
  343.  
  344.      ──────────────────────────────────────────────────────────────────────
  345.           -Uname
  346.       
  347.      This  option  deletes a  preprocessor  macro. It  is  not an  error to
  348.      specify  a macro which was  not defined. It is  an error to attempt to
  349.      undefine:
  350.       
  351.           '__TIME__', '__DATE__', '__FILE__', or '__LINE__'.
  352.       
  353.      It can be used to undefine
  354.       
  355.           '__CLINT__' or '__DOS__'
  356.       
  357.      or  any  symbols defined  in CLINT.CFG.  As with  '-D' you  can append
  358.      several names with ';' like this:
  359.       
  360.       -Uname1;name2
  361.       
  362.      The order of '-D' and '-U' is important - you may only undefine macros
  363.      whose definition precedes the '-U' option.
  364.       
  365.      ──────────────────────────────────────────────────────────────────────
  366.           -o file
  367.           -O file
  368.           -ofile
  369.           -Ofile
  370.       
  371.      This option specifies a file to receive CLint's output. By default the
  372.      output  is written  to 'stderr'. If  you use this  option, CLint still
  373.      writes  the source file name it is  working on to 'stderr' to show you
  374.      how  it is proceeding.  If more than  one of these  options occur, the
  375.      rightmost one is used.
  376.       
  377.      ──────────────────────────────────────────────────────────────────────
  378.           -e0
  379.       
  380.      By  default CLint stops reading a file  if 15 errors are produced, and
  381.      proceeds  to the next file with the  message 'Too many errors'. If you
  382.      use this option the limit is removed.
  383.       
  384.      ──────────────────────────────────────────────────────────────────────
  385.           -eNNN
  386.       
  387.      Use  this option to specify  the error limit you  need. The default is
  388.      15.  If this  option and  '-e0' occur  together, the  rightmost one is
  389.      obeyed.
  390.       
  391.      ──────────────────────────────────────────────────────────────────────
  392.           -w0
  393.           -W0
  394.       
  395.      By  default, CLint stops  reading a file if  60 warnings are produced,
  396.      and proceeds to the next file with the message 'Too many warnings'. If
  397.      you use this option the limit is removed.
  398.       
  399.      ──────────────────────────────────────────────────────────────────────
  400.           -wNNN
  401.       
  402.      Use  this option to specify the warning limit you need. The default is
  403.      60.  If this  option and  '-w0' occur  together, the  rightmost one is
  404.      obeyed.
  405.       
  406.      ──────────────────────────────────────────────────────────────────────
  407.           -wall
  408.       
  409.      A  number of CLint's  warnings are optional, and  OFF by default. This
  410.      turns all warnings on. See the section on warnings for more details.
  411.       
  412.      ──────────────────────────────────────────────────────────────────────
  413.           -w-all
  414.       
  415.      This turns all warnings off. It may usefully occur in CLINT.CFG when
  416.      followed by '-wxxx' options to turn on only those warnings you need.
  417.       
  418.      ──────────────────────────────────────────────────────────────────────
  419.           -wxxx
  420.       
  421.      Turn the specified warning on.
  422.       
  423.      ──────────────────────────────────────────────────────────────────────
  424.           -w-xxx
  425.       
  426.      Turn the specified warning off.
  427.  
  428.      ──────────────────────────────────────────────────────────────────────
  429.       
  430.      This is the complete list of warning switches. Any of them may be used
  431.      in  CLINT.CFG or  on the  command line.  Unless changed  by CLINT.CFG,
  432.      those switches marked with '*' are enabled by default.
  433.       
  434.        wcom         warn of nested comments
  435.        webr         else needs '{'
  436.        wfbr         for needs '{'
  437.        wibr         if needs '{'
  438.        wwbr         while needs '{'
  439.        wspc         advise on spacing
  440.        wlfb         warn of functions longer than 120 lines
  441.        wlfbNNN      warn of functions greater than NNN lines long
  442.        wtyb         typedefing primitive types
  443.       *wtye         warn of typedefing enums
  444.       *wtyg         warn of general (complex) typedefs
  445.       *wtyp         warn of typedefing pointer types
  446.       *wtys         warn of typedefed structs with lower case names
  447.        wtysU        typedefed structs with names not fully in upper case
  448.       *wstv         warn of passed/returned structs (by value)
  449.       *wcon         warn of constant conditions
  450.       *whdr         show warnings in user header files
  451.        wshd         show warnings in system header files
  452.       *wprn         warn of misuse of printf (sprintf, fprintf, etc)
  453.       *wenu         warn of enum misuse
  454.       *wtri         warn about trigraphs
  455.       *winc         warn of multiply included header files
  456.       *wiag         warn of auto aggregate initialisation
  457.       *wunr         warn of unreachable code
  458.       *welb         warn of empty loop bodies
  459.       *wcil         long constant needs 'L'
  460.       *wsig         warn of loss of significance with longs
  461.        wsig+        warn of loss of significance with any type
  462.       *wmxp         warn of mixed pointers to signed/unsigned char
  463.       *wenu         warn of enum missuse
  464.       *wnus         warn of variables defined but not used
  465.       *wpro         warn of function use without a prototype
  466.       *wret         warn of return missuse
  467.  
  468.  
  469.                                 SPECIAL OPTIONS
  470.                                 ───────────────
  471.       
  472.           -L file
  473.       
  474.      This  important option  instructs CLint  to change  it's behaviour, in
  475.      that  it knows that the source files will be headers not program text.
  476.      Each  prototype or external declaration in the source files is written
  477.      to  the 'file' in  a form to be  later read into  CLint using the '-l'
  478.      option.
  479.       
  480.      Note  that many errors will  be reported if this  option is applied to
  481.      program  source, and that the  '-L' MUST be upper  case. The file name
  482.      case is only important if your operating system requires.
  483.       
  484.      ──────────────────────────────────────────────────────────────────────
  485.           -lfile
  486.       
  487.      This  option  instructs CLint  to  read a  definition  file previously
  488.      prepared  with the '-L'  option above. Declarations  and usage in your
  489.      program  files will  be compared to  those recorded  in the definition
  490.      file, and may result in the warning:
  491.       
  492.           Warning: 'name' in file(NNN) hides a library symbol in 'file'
  493.       
  494.      If this happens, you have defined a function or variable which is also
  495.      defined in a library. C allows this, but in some cases it may be a bug
  496.      in your code.
  497.       
  498.       ──────────────────────────────────────────────────────────────────────
  499.          IMPORTANT !! IMPORTANT !! IMPORTANT !! IMPORTANT !! IMPORTANT
  500.       ──────────────────────────────────────────────────────────────────────
  501.      The  '-l' option may be  used differently in CLINT.CFG:  you can use a
  502.      directory name. For example, suppose that you place all the definition
  503.      files you created with the '-L' option above in
  504.       
  505.           \CLINT\MYLIBS
  506.       
  507.      If you want CLint to check usage in ALIB in this directory, you place:
  508.       
  509.           -l\clint\mylibs
  510.       
  511.      in CLINT.CFG, and on the command line use:
  512.       
  513.           -lalib
  514.  
  515.  
  516.                               CONTROL OF TYPEDEFS
  517.                               ───────────────────
  518.       
  519.      'typedef'  is often  misused. You  can control  the way  CLint reports
  520.      these misuses in a number of ways:
  521.       
  522.      ──────────────────────────────────────────────────────────────────────
  523.      -wtye enables reports of typedefing enums, for example:
  524.       
  525.           typedef enum { A, B} THING;
  526.       
  527.      provokes   the  report:  "typedefed  enum  as  'THING'".  We  consider
  528.      typedefing enums to be poor practise as discussed elswhere, except for
  529.      the example given below.
  530.       
  531.      ──────────────────────────────────────────────────────────────────────
  532.      -wtys  enables reports about  typedefing structs or  unions without an
  533.      initial  capital letter in the name, -wtysU enables reports about this
  534.      without  the name being all upper case.  We consider that at least the
  535.      name should start with a capital letter, preferably all upper case.
  536.       
  537.      ──────────────────────────────────────────────────────────────────────
  538.      -wtyp enables reports about typedefing pointer types. We consider this
  539.      to be one of the major abuses of typedef.
  540.       
  541.      ──────────────────────────────────────────────────────────────────────
  542.      -wtyg  enables reports about strange  typdefs - for example typedefing
  543.      an  array. We  produce this message  for any typedef  which is complex
  544.      (not  a  primitive type,  struct,  union, enum,  or  pointer). Complex
  545.      typedefs   are  in  our  opinion  dangerous  as  they  hide  too  much
  546.      information.
  547.       
  548.      ──────────────────────────────────────────────────────────────────────
  549.      -wtyb  enables reports about typedefing  primitive types such as 'int'
  550.      with names that are not all lower case. There are occasions where this
  551.      is  useful, but  we believe that  for clarity the  typedef name should
  552.      always be lower case.
  553.